package com.ruoyi.web.controller.jiaxiao;
// 导入所需的Java工具类
import java.util.List;
// 导入Spring框架相关注解和类
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;
// 导入若依框架相关注解和类
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.enums.BusinessType;
// 导入实体类和服务接口
import com.ruoyi.system.domain.JxStudentProgress;
import com.ruoyi.system.service.IJxStudentProgressService;

/**
 * 驾校学员进度控制器
 * 处理与学员学习进度相关的HTTP请求
 */
@RestController  // 标识这是一个REST风格的控制器，返回结果自动转为JSON
@RequestMapping("/jiaxiao/progress")  // 定义请求路径前缀，所有接口都以该路径开头
public class JxStudentProgressController extends BaseController {  // 继承基础控制器，获取通用功能

    // 自动注入学员进度服务接口，用于调用业务逻辑层方法
    @Autowired
    private IJxStudentProgressService service;

    /**
     * 查询学员进度列表
     * @param query 包含查询条件的实体对象
     * @return 分页后的表格数据
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:list')")  // 权限控制，只有拥有指定权限的用户可访问
    @GetMapping("/list")  // 处理GET请求，完整路径为/jiaxiao/progress/list
    public TableDataInfo list(JxStudentProgress query) {
        startPage();  // 开始分页，从请求中获取分页参数
        List<JxStudentProgress> list = service.selectList(query);  // 调用服务层方法查询列表
        return getDataTable(list);  // 封装分页结果并返回
    }

    /**
     * 获取学员进度详情
     * @param id 学员进度记录ID
     * @return 包含学员进度详情的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:query')")  // 权限控制
    @GetMapping("/{id}")  // 处理GET请求，路径为/jiaxiao/progress/{id}，{id}为路径参数
    public AjaxResult getInfo(@PathVariable Long id) {  // @PathVariable获取路径中的id参数
        return AjaxResult.success(service.selectById(id));  // 调用服务层查询详情并返回成功结果
    }

    /**
     * 新增学员进度记录
     * @param entity 包含新增数据的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:add')")  // 权限控制
    @Log(title = "学习进度", businessType = BusinessType.INSERT)  // 记录操作日志，标题为"学习进度"，类型为插入
    @PostMapping  // 处理POST请求，路径为/jiaxiao/progress
    public AjaxResult add(@RequestBody JxStudentProgress entity) {  // @RequestBody接收请求体中的JSON数据并转为实体
        return toAjax(service.insert(entity));  // 调用服务层新增方法，将结果转为AjaxResult返回
    }

    /**
     * 修改学员进度记录
     * @param entity 包含修改数据的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:edit')")  // 权限控制
    @Log(title = "学习进度", businessType = BusinessType.UPDATE)  // 记录操作日志，类型为更新
    @PutMapping  // 处理PUT请求，路径为/jiaxiao/progress
    public AjaxResult edit(@RequestBody JxStudentProgress entity) {  // 接收请求体中的JSON数据
        return toAjax(service.update(entity));  // 调用服务层更新方法，返回操作结果
    }

    /**
     * 删除学员进度记录
     * @param ids 要删除的记录ID数组
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:remove')")  // 权限控制
    @Log(title = "学习进度", businessType = BusinessType.DELETE)  // 记录操作日志，类型为删除
    @DeleteMapping("/{ids}")  // 处理DELETE请求，路径为/jiaxiao/progress/{ids}
    public AjaxResult remove(@PathVariable Long[] ids) {  // 获取路径中的ID数组
        return toAjax(service.deleteByIds(ids));  // 调用服务层批量删除方法，返回操作结果
    }

    /**
     * 为学员增加学习时长
     * @param id 学员进度记录ID
     * @param delta 要增加的时长
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:progress:edit')")  // 权限控制
    @Log(title = "学习进度加时", businessType = BusinessType.UPDATE)  // 记录操作日志，标题为"学习进度加时"
    @PutMapping("/addHours/{id}")  // 处理PUT请求，路径为/jiaxiao/progress/addHours/{id}
    public AjaxResult addHours(@PathVariable Long id, @RequestParam int delta) {  // 获取路径参数id和请求参数delta
        return toAjax(service.addHours(id, delta));  // 调用服务层增加时长方法，返回操作结果
    }
}